home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 January: Mac OS SDK / Dev.CD Jan 98 SDK1.toast / Development Kits (Disc 1) / QuickDraw 3D / RAVE SDK 1.5 MacOS / Projects / S3V Docs / Sneak3view Documentation < prev    next >
Encoding:
Text File  |  1997-08-14  |  33.3 KB  |  775 lines  |  [TEXT/MPS ]

  1. Sneak3view 
  2. ==========  
  3.  
  4. Version 1.4
  5.  
  6.  
  7. 3/29/96
  8.  
  9.  
  10.  
  11.  
  12.  
  13. Introduction
  14. ============
  15.  
  16. Sneak3view is a tool for debugging and testing RAVE drawing engines.  A 
  17. humble objective, to be sure, but one it tackles with brio.
  18.  
  19. The advantage of using Sneak3view is that it makes flipping all of RAVE's 
  20. switches very easy.  You can quickly change the texture maps and the 
  21. background color, turn double-buffering on and off, etc., all without 
  22. changing your code.  Additionally, the same test is run simultaneously in 
  23. two different draw contexts.  This lets you compare the output of your 
  24. engine with one that you know works correctly (e.g., the Apple Software 
  25. rasterizer).
  26.  
  27. The basic procedure for debugging your engine is as follows: write a test 
  28. in C which exercises some part of your raterizer, say, textured triangles.  
  29. Compile the test into Sneak3view and run the app.  Select the engines and 
  30. the test you want to use from the appropriate pop-up menus in the settings 
  31. window.  Set the RAVE state variables the way you want them and run the 
  32. test.  When it's complete, compare the engines' output with the image you 
  33. expected.  If it's not right, tweak your engine and run the test again.
  34.  
  35.  
  36. What You Need
  37. ==== === ====
  38.  
  39.     • a PowerMac
  40.     • System 7.5.1 or later
  41.     • the QuickDraw 3D RAVE extension
  42.     • the RAVE engines you want to test
  43.     • CodeWarrior 8.0
  44.     • 2Mb - 3Mb of free memory to run Sneak3view 
  45.     • 16-bit or 24-bit color (unless your drawing engine supports 8-bit)
  46.     • familiarity with the RAVE API 
  47.     
  48. Make sure you have the necessary extensions and system before running 
  49. Sneak3view.  It is not terribly forgiving of environments it doesn't like.
  50.  
  51.  
  52. IMPORTANT
  53. =========
  54.  
  55. Sneak3view now requires the Display Manager 2.0 to be present.  This 
  56. library should be built into every system after 7.5.  Or you can add it
  57. through an extension that is available with the Display Manager SDK.
  58.  
  59.  
  60. What's New
  61. ====== === 
  62.  
  63. • The output from the timing tests is much more informative.  In 
  64.   addition to having a better format, it now also prints out the size of 
  65.   the test windows and the bitdepth and size of the monitor(s).  Since  
  66.   these values can affect the rendering speed, it's helpful to have them 
  67.   displayed in when comparing test runs.
  68.   
  69. • Added the ability to call one test from another.  This lets you group a 
  70.   number of tests together into one composite test so that they all get 
  71.   run, one after the other.  "Game Scene (Every Format)" is an example of 
  72.   this. 
  73.   
  74. • Some tests can now be cancelled by typing command-period (principally the 
  75.   "random" tests).  
  76.  
  77. • The timing information that used to be printed out after every test has 
  78.   been removed, since it wasn't really relevant.
  79.  
  80. • Fixed the bug in the timing tests that sometimes produced 1- or 2-pixel 
  81.   borders between the triangles.  
  82.  
  83. • Fixed a bug that caused textures that were 1 pixel wide or high to be 
  84.   mipmapped incorrectly.
  85.  
  86. • Finally fixed that benign but annoying write-to-nil bug.
  87.  
  88.  
  89. Setting Up Sneak3view
  90. ======= == ==========
  91.  
  92. The best place to put Sneak3view is simply to leave it where it is in the 
  93. RAVE DDK hierarchy.  That way, the CodeWarrior project's access paths will 
  94. all be correct.
  95.  
  96. For Sneak3view to find your engine, it must reside somewhere the RAVE 
  97. manager can find it, i.e., either in the Extensions folder or the same 
  98. folder as Sneak3view.  What that used to mean was that every time you built 
  99. a new version of your engine, you would have to copy it over to 
  100. Sneak3view's folder.  Fortunately, the RAVE manager will now follow aliases 
  101. when looking for engines.  Simply put an alias to your engine either in the 
  102. Extensions folder or in Sneak3view's folder so that it will always use the 
  103. latest version.
  104.  
  105. If you have particular PICT files you want to use as textures or bitmaps, 
  106. place them anywhere inside the Sneak3view folder.  Sneak3view will search 
  107. its entire folder hierarchy for PICTs when it starts up.  A number of 
  108. textures are included with the RAVE DDK, inside the Textures folder.  Some 
  109. tests, such as the Game Scene, may expect particular textures to be available 
  110. when they run, so it's best to leave the existing ones where they are.  
  111. Note that Sneak3view currently does not follow aliases when looking for 
  112. PICT files. 
  113.  
  114.  
  115. Settings
  116. ======== 
  117.  
  118. RAVE has numerous state variables and flags which affect how a drawing 
  119. engine rasterizes the triangles you submit to it.  These variables are 
  120. controlled by Sneak3view's settings windows.  Each control corresponds to 
  121. some aspect of a RAVE draw context, texture or bitmap.
  122.  
  123. When launched, Sneak3view opens a new, untitled settings document for you 
  124. to work with.  If you launch it instead by opening one or more of its 
  125. documents in the Finder, Sneak3view will not open a blank document.
  126.  
  127. Each settings window is a separate document.  When you run a test, the 
  128. values in the topmost settings window are the ones in effect.  For 
  129. instance, the settings window contains fields which control the size and 
  130. position of the test windows.  When you click on a settings window to bring 
  131. it forward, the test windows will move and resize themselves to reflect the 
  132. values in that settings document.
  133.  
  134. The settings you select can be saved into a Sneak3view document by choosing 
  135. Save or Save As...  from the File menu.  The position of a document window 
  136. is saved when it is closed and restored the next time it is opened 
  137. (assuming you didn't close it without saving the changes).  Printing is not 
  138. currently supported.  The settings data is stored in the file's resource 
  139. fork, while the test output is saved in the data fork.  This means that if 
  140. you change the file's type to TEXT or use an editor like Alpha which can 
  141. load files of any type, then you can read the test output into a text 
  142. editor.
  143.  
  144. Selecting the Duplicate command from the File menu creates a new settings 
  145. window that is identical to the frontmost one.  This is useful when you 
  146. want to quickly compare the effects of varying a few of the settings, for 
  147. instance, RGB-32 vs.  ARGB-16 and mipmapping on vs.  off.  Rather than 
  148. manually changing them back and forth each time you run the test, set the 
  149. controls one way (RGB-32, mipmapping on), duplicate the window, and then 
  150. set a few of them the other way (ARGB-16, mipmapping off).  Now you can run 
  151. a test using these settings simply by clicking on the Run button in either 
  152. of these windows.
  153.  
  154. Normally when you close a document without saving the changes, Sneak3view 
  155. makes sure that you really want to do that.  However, if the document is 
  156. called "Untitled Settings," its settings will automatically be recorded in 
  157. "Sneak3view Prefs," inside the Preferences folder.  The next time 
  158. Sneak3view is launched by double-clicking, it will load those settings 
  159. back into a new, untitled window.  This way, if you only ever use a single 
  160. window, you can just quit the application without worrying about saving 
  161. the settings to a particular file.  The text output section of the settings 
  162. window, however, is not saved into the prefs file.
  163.  
  164. Because it has so many controls, the settings window can take a long time 
  165. (a second or two) to redraw.  This can be quite annoying when you are 
  166. single-stepping through your code and Sneak3view redraws the window every 
  167. time the debugger switches back to it.  Fortunately it is possible to turn 
  168. off the window redraw by command-clicking in a blank part of the settings 
  169. window (a good place is next to the Run button).  You will hear a beep to
  170. indicate that the settings windows will not redraw themselves until you 
  171. command-click again.
  172.  
  173. The settings window's controls are split into five tabbed sections.  To 
  174. display a particular section, simply click on its tab.  Each of these 
  175. sections is described in detail below.
  176.  
  177.  
  178. Windows
  179. ------- 
  180.  
  181. The window settings effect the size and position of the test windows.  
  182. Rather unsurprisingly, the Width and Height text fields control the width 
  183. and height, respectively, of the test windows.  The windows resize 
  184. themselves in response to each character you type into or delete from the 
  185. field.  For example, if you type "2," then "0," then "0" into the width 
  186. field, the test windows' width will be 2 pixels, then 20 pixels, then 200 
  187. pixels.  Deleting all the text from a text field sets that field's value 
  188. to 0.
  189.  
  190. There are also two sets of Left and Top test fields, one under the Left 
  191. Engine popup menu and one under the Right.  These fields specify the 
  192. positions of the top-left corners of the Left and Right test windows.  
  193. (Determining which fields control which window is left(!) as an excercise 
  194. for the reader.)  As with the Width and Height fields, the Left and Top 
  195. fields are "live," so the appropriate test window will reposition itself 
  196. in response to each number you type.
  197.  
  198. The values for the Left and Top fields are given in global screen 
  199. coordinates.  This means that if you have a second monitor to the left of 
  200. the main one and position a test window on it, the window's left value 
  201. will be negative.
  202.  
  203. The Reset Windows button returns the test windows to their default position 
  204. (on the monitor with the greatest color depth) and shape (square).  
  205. Clicking this button is a quick way to make the test windows visible again, 
  206. in case they appear off-screen for some reason (as might happen if you move 
  207. the menu bar to a different monitor).
  208.  
  209. The left and right engine pop-up menus determine which engine is called to 
  210. perform a particular test.  When Sneak3view starts up, it calls 
  211. QAGetFirstEngine and then QAGetNextEngine to find every available 
  212. RAVE drawing engine.  It finds only those engines which are either in 
  213. the Extensions folder or are in the same folder as the application itself.  
  214. If you add a new engine while Sneak3view is running, you must quit and 
  215. restart the app before it will recognize the new engine.
  216.  
  217. The name of the currently-selected engine will appear in the title bar of 
  218. the corresponding test window.  Selecting the same engine in both pop-up 
  219. menus will work just fine.
  220.  
  221.  
  222. Draw Context
  223. ---- -------
  224.  
  225. This section of the settings window contains eight pop-up menus which 
  226. affect the type of draw context which is created for your test.  Some of 
  227. them control flags which are passed to QADrawContextNew to create a new 
  228. draw context and some of them control state variables which are set after 
  229. the context is created, but before any test is run.
  230.  
  231. Many of the items in these menus represent specific RAVE constants.  
  232. To see the relationships, look in the PvalDefs.r file, inside the Resources 
  233. folder.  Each item in a 'Pval' resource corresponds directly to an item in 
  234. the menu.
  235.  
  236.  
  237.     Device:
  238.         In RAVE, you can draw to either a window or a part of memory.  
  239.         Selecting Window from the Device menu causes the test to draw directly to 
  240.         the screen.  If you select Memory 16-bit or 32-bit, the test will draw
  241.         into off-screen memory, which is then copied to the screen.
  242.     
  243.         The setting of the Device menu has important implications for what you 
  244.         actually end up seeing after running a test.  With Window selected, the 
  245.         RAVE engine creates a draw context with the same bit-depth as the 
  246.         screen on which its test window is positioned.  When you select one of 
  247.         the memory options, both engines draw into a context with the same bit 
  248.         depth, either 16 or 32, regardless of what your monitor supports.  The 
  249.         off-screen memory is then copied to the screen using CopyBits.
  250.         
  251.         As an example, say you have two screens.  The one on the left supports 
  252.         16-bit color and the one on the right, 32-bit color.  If you position 
  253.         one window on each monitor, the left engine will draw into a 16-bit 
  254.         context and the right into a 32-bit one.  The pixels you see on the 
  255.         screen are exactly the same as the pixels the drawing engine produced.  
  256.         
  257.         Now assume you set one monitor to 8-bit and one to 16-bit, and then 
  258.         select Memory 32-bit from the Device menu.  Both engines will draw into a 
  259.         context with the same bitdepth, but what you see on the screen will vary 
  260.         considerably.  Color resolution will be lost as CopyBits draws the 
  261.         32-bit pixels onto the 8-bit and 16-bit screens.  
  262.         
  263.         The upshot of all this is simply to be aware of the color depth of your 
  264.         monitor(s) and how it compares to the depth of the device type you've 
  265.         chosen with this menu.  
  266.         
  267.         Note that if an engine does not support a monitor's current bit-depth 
  268.         and the device menu is set to Window, you will get an alert message 
  269.         saying that the engine does not support the current device type.  This 
  270.         does not mean the engine cannot support the Window device type, only 
  271.         that it requires a different bit-depth.  Either change the monitor's 
  272.         bit-depth or move the windows to a monitor which has an appropriate 
  273.         number of colors.
  274.  
  275.     
  276.     Clipping Region:
  277.         One of the parameters that is passed to QADrawContextNew is a pointer to 
  278.         a TQAClip.  On the Macintosh, a TQAClip contains a handle to a region.  
  279.         The Clipping Region menu offers a choice of five different clipping 
  280.         regions, or none at all.  The regions are constructed relative to the 
  281.         size of the test windows.  Their effects should be clear from their 
  282.         names.  If you want to add new types of clipping regions, you'll have to 
  283.         modify CTestInfo::MakeClipRegion in CTestInfo.cp, the PvalDefs.r file and
  284.         the Clipping Region menu resource in Sneak3view.rsrc.
  285.         
  286.     
  287.     Buffering:
  288.         This menu controls part of the setting of the flags parameter that is 
  289.         passed to QADrawContextNew.  It determines whether the 
  290.         kQAContext_DoubleBuffer bit is set or not.
  291.         
  292.     
  293.     Z Buffering:
  294.         This menu affects another part of the flags parameter, the 
  295.         kQAContext_DeepZ and kQAContext_NoZBuffer bits.  The menu items 
  296.         represent the following bit combinations:
  297.         
  298.             None:    kQAContext_NoZBuffer = 1, kQAContext_DeepZ = 0
  299.             Shallow: kQAContext_NoZBuffer = 0, kQAContext_DeepZ = 0
  300.             Deep:    kQAContext_NoZBuffer = 0, kQAContext_DeepZ = 1
  301.         
  302.         The remaining combination of bits (1,1) is illegal. 
  303.         
  304.         
  305.     Z Function:
  306.         The required kQATag_ZFunction state variable is set through this menu.  
  307.         The OpenGL specific options in this menu are currently disabled.  You 
  308.         will have to enable them with ResEdit if you're creating an OpenGL-
  309.         compliant drawing engine.
  310.         
  311.     
  312.     Perspective Z:
  313.         This menu is a simple toggle for the optional kQATag_PerspectiveZ state 
  314.         variable.
  315.         
  316.         
  317.     Blending:
  318.         The setting of this menu controls the optional kQATag_Blend state 
  319.         variable.  Again, the OpenGL option is disabled, and can be re-enabled 
  320.         with ResEdit.
  321.         
  322.         
  323.     Antialiasing:
  324.         This menu represents the value of the option kQATag_Antialias state 
  325.         variable.  
  326.         
  327.  
  328.     Test Arguments:
  329.         This text field accepts a 255-character string, which Sneak3view makes 
  330.         available to your test as a C-string.  You can access it with the
  331.         S3TestInfo_GetArgString() function.  It is up to you to decide how your 
  332.         tests will parse and respond to the contents of this field.  Every time 
  333.         you change the Test popup menu, the Test Arguments field is cleared.  
  334.         This is done to help you avoid using an inappropriate argument string 
  335.         with the newly-selected test.
  336.         
  337.  
  338. Color/Line
  339. ---------- 
  340.  
  341.     Background: 
  342.         The four text fields labeled A(lpha), R(ed), G(reen), B(lue) control 
  343.         the background color of the draw context (the kQATag_ColorBG_a/r/g/b 
  344.         state variable).  The context is filled with this color before drawing 
  345.         begins.  Acceptable values are floating point numbers between 0 and 1, 
  346.         although Sneak3view will set these variables to whatever values you 
  347.         give it.
  348.         
  349.     
  350.     Line Width:
  351.         This text field controls the required kQATag_Width state variable, which 
  352.         affects the width of lines and points.  Acceptable values are currently 
  353.         between 1.0 and 128.0, but Sneak3view will set the variable to whatever 
  354.         number you enter.
  355.         
  356.  
  357. Texture
  358. ------- 
  359.  
  360. Through the RAVE API, you can create as many textures as a particular 
  361. drawing engine can handle.  However, to make it easier to test your engine 
  362. on different textures, Sneak3view lets you select a single PICT file as a 
  363. texture.  Before the test is run, it creates a new texture from that file 
  364. for each of the selected engines and sets the kQATag_Texture state variable 
  365. in each draw context to point to the appropriate texture.
  366.  
  367. If you write a test that requires a texture or bitmap, you must specify 
  368. that prerequisite when you register the test.  That way Sneak3view can alert 
  369. the user that the test cannot be run until a texture is selected.
  370.  
  371. The other variables that affect how a texture is drawn, such as 
  372. kQATag_TextureFilter, are controlled by the checkboxes and pop-up menus in 
  373. this section.
  374.  
  375.  
  376.     Texture:
  377.         When Sneak3view starts up, it searches its folder and all its 
  378.         subfolders for PICT files.  It lists in this menu the first 80 that 
  379.         it finds.  So the simplest way to use textures in your tests is to 
  380.         store them as PICTs in a folder inside Sneak3view's folder.  If you 
  381.         want to use a file which does not appear in this menu, select the 
  382.         Choose...  command.  This opens the standard file dialog from which 
  383.         you can pick a PICT file.  The file's name is added to the end of 
  384.         the pop-up menu.
  385.         
  386.         Also note that an alias to the texture file is recorded when the 
  387.         settings document is saved, so Sneak3view should be able to find the 
  388.         texture the next time you open the document, even if you move or rename 
  389.         it.
  390.  
  391.  
  392.     Texture Format:
  393.         This menu controls the value of the pixelType parameter which is 
  394.         passed to QATextureNew.  Note that this menu's setting is 
  395.         independent of the PICT file's actual bit-depth.  The PICT is 
  396.         simply drawn into an off-screen GWorld, so you can take an 8-bit 
  397.         PICT file with no alpha channel and create a 32-bit ARGB texture 
  398.         from it.  However, in this case, the alpha channel will be 
  399.         completely blank, which means that it will be invisible unless you 
  400.         check Make Black Transparent.
  401.         
  402.         If you've stored an 8-bit alpha channel in a 32-bit PICT (using 
  403.         Photoshop, for instance), those alpha values will be used in the 
  404.         texture.  It may also be possible to set the alpha bit in a 16-bit 
  405.         PICT and have that alpha channel used in the texture, although that has 
  406.         not been tested.  Another way of creating an alpha channel is to use the 
  407.         Make Black Transparent option described below.
  408.         
  409.         When you select 16-bit RGB or 32-bit RGB, the drawing engine should 
  410.         ignore the alpha channel completely, so it shouldn't matter what you have 
  411.         in it.
  412.         
  413.  
  414.     Texture Filter:
  415.         This menu controls the optional kQATag_TextureFilter state variable.
  416.         
  417.         
  418.     Texture Op:
  419.         These checkboxes control the optional kQATag_TextureOp bit mask.  
  420.         Unchecking all of the boxes is equivalent to the kQATextureOp_None 
  421.         constant.  
  422.         
  423.         
  424.     Create Mipmap:
  425.         This option causes Sneak3view to pass an array of images to 
  426.         QATextureNew, rather than just a single image, as well as setting the 
  427.         kQATexture_Mipmap bit in the flags parameter.  The mipmaps are created 
  428.         using a 2 X 2 pixel square filter on the selected PICT.  If you want to 
  429.         create your own mipmaps, you'll have to read in the PICT yourself 
  430.         during the test and do your own filtering on it.
  431.         
  432.         The alpha channel as well as the RGB channels are affected by the 
  433.         mipmapping process.
  434.         
  435.         
  436.     Lock Texture:
  437.         Checking this box sets the kQATexture_Lock bit in the flags parameter to 
  438.         QATextureNew.
  439.         
  440.         
  441.     Detach Texture:
  442.         This option determines whether QATextureDetach is called after the 
  443.         texture has been created.  If an engine returns an error in response to 
  444.         QATextureDetach, Sneak3view will produce an alert and will not run the 
  445.         test.
  446.         
  447.         
  448.     Make Black Transparent:
  449.         This is a purely Sneak3view option which causes the app to create 
  450.         an alpha channel for the selected PICT. Every completely black 
  451.         pixel in the PICT will have its alpha channel set to 0 
  452.         (transparent) and every non-black pixel's alpha channel will be set 
  453.         to 255 (for 32-bit) or 1 (for 16-bit).  This is a useful way of 
  454.         quickly creating an alpha channel for a texture that does not have 
  455.         one.
  456.  
  457.  
  458.     Color Table:
  459.         When the texture format is set to 4-bit or 8-bit Color Lookup, the 
  460.         Color Table menu and the adjacent checkbox become active.  
  461.         Currently, the only available item on this menu is Default.  With 
  462.         this item selected, the color table that is applied to the texture 
  463.         will be derived from the colors that are actually used in the PICT 
  464.         file.  If the PICT is in 4- or 8-bit format, the file's exact color 
  465.         table will be used.  Otherwise, QuickDraw will determine a suitable 
  466.         set of colors.
  467.     
  468.         Eventually, it will be possible to apply a color table from an 
  469.         arbitrary file to the current texture.
  470.  
  471.  
  472.     Color 0 is Transparent:
  473.         The call which binds a RAVE color table to a texture has a 
  474.         parameter which determines whether the first color in the table 
  475.         (index 0) is transparent.  To force any pixel which has index 0 to 
  476.         be transparent, check this box.  Otherwise, the color stored in 
  477.         element 0 will be drawn.
  478.         
  479.  
  480. Bitmap
  481. ------
  482.  
  483. Sneak3view handles bitmaps similarly to textures.  You have the option of 
  484. selecting one bitmap which will be created for each engine before the test 
  485. is run.
  486.  
  487.  
  488.     Bitmap:
  489.         This menu is identical to the Texture pop-up menu, listing exactly the 
  490.         same PICT files.  However, bitmaps are not required to have dimensions 
  491.         that are powers of 2 and may be 1-bit deep, so PICTs that are suitable 
  492.         for use as a bitmap are not necessarily usable as a texture.  
  493.         
  494.         The Choose... command in both the Bitmap and Texture pop-ups is 
  495.         equivalent.  Any file you select with it will be added to both menus. 
  496.         
  497.         
  498.     Bitmap Format:
  499.         Besides the options available in the Texture Format menu, you may 
  500.         also choose a 1-bit alpha format.  With this choice selected, every 
  501.         non-zero pixel in the bitmap will be colored with the RGB values 
  502.         which are passed into QADrawBitmap (individual tests are 
  503.         responsible for setting the bitmap color), while the zero-value 
  504.         pixels will be transparent.  In this case, the Make Black 
  505.         Transparent option is ignored.
  506.         
  507.  
  508.     Detach Bitmap:
  509.         This checkbox is equivalent to the one for textures.  It calls 
  510.         QABitmapDetach for the selected bitmap after it has been created.
  511.         
  512.     
  513.     Lock Bitmap:
  514.         Again, this option is identical to the texture version.  It controls the 
  515.         value of the kQABitmap_Lock bit in the flags parameter to QABitmapNew.
  516.         
  517.  
  518.     Make Black Transparent:
  519.         Like the texture option, this checkbox causes Sneak3view to turn the 
  520.         black pixels in the bitmap transparent.  It is ignored if Bitmap Format 
  521.         is set to 1-bit A.
  522.  
  523.  
  524.     Color Table:
  525.         When the bitmap format is set to 4-bit or 8-bit Color Lookup, the 
  526.         Color Table menu and the adjacent checkbox become active.  
  527.         Currently, the only available item on this menu is Default.  With 
  528.         this item selected, the color table that is applied to the bitmap 
  529.         will be derived from the colors that are actually used in the PICT 
  530.         file.  If the PICT is in 4- or 8-bit format, the file's exact color 
  531.         table will be used.  Otherwise, QuickDraw will determine a suitable 
  532.         set of colors.
  533.     
  534.         Eventually, it will be possible to apply a color table from an 
  535.         arbitrary file to the current bitmap.
  536.  
  537.  
  538.     Color 0 is Transparent:
  539.         The call which binds a RAVE color table to a bitmap has a parameter 
  540.         which determines whether the first color in the table (index 0) is 
  541.         transparent.  To force any pixel which has index 0 to be 
  542.         transparent, check this box.  Otherwise, the color stored in 
  543.         element 0 will be drawn.
  544.                 
  545.  
  546. Test
  547. ---- 
  548.  
  549. These controls are situated just below the tabbed sections and are always 
  550. visible.
  551.  
  552.  
  553.     Test:
  554.         This popup-up lists all the tests you have registered in 
  555.         S3TestRegister.  The test you select will be executed when you click the 
  556.         Run button.
  557.         
  558.     
  559.     Reset Random Seed:
  560.         When this option is checked, Sneak3view resets the seed used by the 
  561.         S3TestUtil_RandomFloat function.  Any test which uses this function (or 
  562.         rand(), which S3TestUtil_RandomFloat calls in turn) will therefore 
  563.         behave exactly the same way each time it is run.  This can be useful when 
  564.         debugging a particular test.
  565.  
  566.  
  567.     Run:
  568.         Clicking this button executes the test that is selected in the 
  569.         Test menu.  It is also possible to run a test by typing command-R or 
  570.         selecting Run Test from the Test menu.  If the test windows are frontmost 
  571.         when you select this menu item or type its shortcut, the test in the 
  572.         topmost settings window will the one that is executed.
  573.         
  574.         Before a test is run, Sneak3view ensures that certain prerequisites are 
  575.         met.  For instance, if the test requires a texture, then you must 
  576.         select a texture before running that test.  (A test's prerequisites are 
  577.         specified when the test is registered, as described in "Writing Sneak3view 
  578.         Tests.")  You will also receive alerts if Sneak3view cannot successfully 
  579.         create a texture or bitmap for some reason, e.g., one of the engines 
  580.         does not support the selected pixel format.  After the test has 
  581.         finished, you will receive an alert as well if it returned a failure code.
  582.         
  583.     
  584.     Test Output:
  585.         The text view at the very bottom of the settings window is where tests 
  586.         can print output using the S3Test_Print routine.  Before a test 
  587.         executes, Sneak3view prints a divider line, the name of the test, and 
  588.         the current time and date.  After a test has finished it prints another  
  589.         divider line.  
  590.                 
  591.         The text view is editable, so you can add your own notes amid the test 
  592.         output.  If you want to quickly delete all of it, choose Select All from 
  593.         the File menu and then press the delete key.  Every time you save a 
  594.         settings document, the output text is saved along with the settings.
  595.         
  596.  
  597. Test Windows
  598. ==== ======= 
  599.  
  600. The test windows are where your Sneak3view tests draw their output.  Each 
  601. window is labeled with the name of the engine which draws there.  The test 
  602. windows cannot be closed or hidden.
  603.  
  604. The size and position of the test windows are controlled by the edit fields 
  605. described above in the Windows subsection.  However, it is also possible to 
  606. drag a window directly.  After the window has been moved, the Left and Top 
  607. edit fields in the frontmost settings document are updated to reflect the 
  608. test window's new position.
  609.  
  610. Similarly, a test window's size can be changed by dragging its lower-right 
  611. corner, even though there is no visible grow icon there.  After you have 
  612. resized one window, the other will adopt the same dimensions, since the 
  613. test windows must always be the same size.
  614.  
  615. When moving or resizing the test windows (either directly or through the 
  616. settings window), make sure they do not overlap or hang off the screen.  
  617. Overlapping or clipped windows will cause problems as the RAVE engines 
  618. draw to the screen.
  619.  
  620. When you click the Run button on a settings window or select Run Test from 
  621. the Test menu, the test windows will move to the front.  After the test 
  622. has finished, the output in each window is saved into an off-screen 
  623. bitmap with the same bit-depth as the window.  This ensures that the 
  624. window will redraw correctly.  It also means that Sneak3view will require 
  625. quite a bit of memory if you use very large, 32-bit windows.  If the app 
  626. cannot allocate enough space in its own heap, it will use System memory.  
  627. If there is still not enough free RAM, the test output will simply not be 
  628. saved.  You can tell this has happened if the window does not redraw when 
  629. covered and then uncovered.  To reduce the memory requirements, use 
  630. smaller windows and/or lower bit-depths.
  631.  
  632. Another benefit of storing the test output in an off-screen bitmap is that 
  633. you can save it to a file.  Click on either test window to bring it forward 
  634. and select Save from the File menu.  You will be asked to supply a name for 
  635. the file; the default name is made up of the current date and time.  Each 
  636. time you select Save, you will need to enter a name.  (Save As...  would 
  637. have been more appropriate, but it's convenient to have a command-key for 
  638. it.) The output is saved as a SimpleText PICT file.  If the Save command is 
  639. disabled, then there is not enough memory to store the test output.
  640.  
  641. Saving the test output is a quick way of creating textures.  Use the height 
  642. and width fields to size the windows so their dimensions are a power of 
  643. two (the dimensions don't have to be identical), or to any value if all you 
  644. want is a bitmap.  Then run a test and save the output in one of the test 
  645. windows.  Select Choose...  from the Texture or Bitmap menus and open the 
  646. PICT file you just saved.  You can now use this PICT as a texture or bitmap 
  647. in any tests that require one.
  648.  
  649. When you resize a window after a test has been run (or switch to a settings 
  650. document that has differently-sized windows), its output will be resized as 
  651. well, most likely distorting the image in the process.
  652.  
  653.  
  654. Output Comparison
  655. ====== ==========
  656.  
  657. Quite often you will be using Sneak3view to compare the output of a drawing 
  658. engine that you know works correctly, such as the Apple Software 
  659. rasterizer, and one which you are debugging.  To quickly spot differences 
  660. between the output of the two engines, you can use Sneak3view's comparison 
  661. functions.
  662.  
  663. Select Compare Windows from the Compare menu to compare the two windows.  
  664. Both windows must have the same bitdepth, either 16-bit or 32-bit.  
  665. Sneak3view will compare each pixel in the two windows and display the 
  666. difference as a greyscale value in a third window.  This third window will 
  667. require as much memory as the other two do.
  668.  
  669. When the comparison window first opens, it will display the average of the 
  670. differences between the two test outputs in each channel.  To display the 
  671. channels separately, select one of the display options in the Compare 
  672. menu, or use command-1 (red) through command-4 (alpha).
  673.  
  674. If you're showing, say, the green channel in the comparison window, a
  675. completely white pixel indicates that the two outputs have an identical 
  676. green component at that position.  A completely black pixel means one engine 
  677. used the lowest green value (0) there and the other used the highest (31 or 
  678. 255).  
  679.  
  680. Typing command-6 or command-7 will display the actual left or right output, 
  681. respectively, in the comparison window.  This lets you quickly flip back 
  682. and forth between one channel and the test output.  The Alternate 
  683. Left/Right command causes the comparison window to continually switch 
  684. between the left and right output, once a second.
  685.  
  686. If the comparison window is open when you run a test, the windows will be 
  687. automatically re-compared after the test has finished.  To stop the 
  688. comparisons, simply close the window.  If the comparison window is open 
  689. when a composite test is run, the output will be compared after each of the 
  690. sub-tests finishes.  If the composite test opens a movable modal dialog 
  691. asking whether you want to go on to the next test, you will be able to 
  692. access the Compare menu while the dialog is open.  
  693.  
  694.  
  695. Known Bugs
  696. ===== ==== 
  697.  
  698. • If the comparison window overlaps the output windows when a composite 
  699.   test finishes, the image of the comparison window will be saved into the 
  700.   test output windows.  
  701.   
  702.   Fix: Do net let the comparison window overlap the output windows when 
  703.   running a composite test or close the comparison window before running it.
  704.  
  705. • There appears to be a bug using 32-bit PICT files that include alpha 
  706.   channels as CL4 or CL8 textures or bitmaps.  GetPictInfo() doesn't seem 
  707.   to return the correct color tables, which produces strangely-colored images.
  708.   
  709.   Fix: Use only PICTs with no alpha channels (less than 32-bit), or 32-bit 
  710.   PICTs with completely white alpha channels, as color-mapped textures and 
  711.   bitmaps.
  712.  
  713. • At the moment, it is not possible to mipmap CL4 or CL8 textures.
  714.  
  715.   Fix: Write your own test and do the mipmapping yourself.
  716.  
  717. • Sometimes resizing the settings window does not cause the test output 
  718.   area to update itself.
  719.   
  720.   Fix: Scroll up and then back down to redraw the text area.
  721.  
  722. • If you have an extension such as Stretch which lets you resize a window 
  723.   by dragging any of its four sizes, the test windows will not behave 
  724.   correctly if you try to resize them by dragging their left or top sides.  
  725.   Also, you will be able to increase the width of the settings windows, 
  726.   which you should not be able to do.  (Only the window's height should be 
  727.   changeable.)
  728.   
  729.   Fix: Don't resize these windows by dragging the left or top sides.
  730.     
  731. • You will not be able to overwrite an existing file when saving a settings 
  732.   document, even when you click the Replace button.
  733.   
  734.   Fix: Delete the file manually before saving a new file with the same name.
  735.     
  736. • There is no way to test the cache option for QADrawContextNew.
  737.  
  738.   Fix: Write a test to do it yourself.
  739.     
  740. • If you collapse a test window using WindowShade and then run a test, the 
  741.   test's output is drawn directly to the screen.  The output will, however, 
  742.   be saved correctly.  When you expand the window again, the test output 
  743.   will be redrawn. 
  744.   
  745.   Fix: Don't run a test when a test window is collapsed.
  746.     
  747. • Moving the menu bar when you have multiple monitors can cause 
  748.   Sneak3view's settings window to open somewhere off the screen.
  749.   
  750.   Fix: Delete Sneak3view's prefs file and run it again.
  751.     
  752.  
  753. Coming Attractions
  754. ====== =========== 
  755.  
  756. • The ability to apply an arbitrary color table to a texture or bitmap.
  757. • Mipmapping for CL4 and CL8 textures.
  758. • A RAVE engine which will save all the triangles and textures passed to it 
  759.   into a file, and a test which will read that file and draw the triangles 
  760.   in Sneak3view.  This lets you quickly generate realistic test scenes by 
  761.   capturing frames from existing software.
  762. • Size, depth, and path information on the selected texture or bitmap.
  763. • A test pane to display the test's prerequisites, a description of what it 
  764.   does, and a list of the arguments it takes.
  765. • Allow settings files to be overwritten.
  766.  
  767.  
  768. Questions?  Comments?  Bugs?
  769. ==========  =========  ===== 
  770.  
  771. If you have any suggestions or bug reports, send them to:
  772.  
  773. <mailto:brent@taurus.apple.com>
  774.  
  775.